/**
 * @file memory_utils.h
 * @brief 内存管理工具函数
 * @author 电网104协议开发团队
 * @date 2024
 */

#ifndef MEMORY_UTILS_H
#define MEMORY_UTILS_H

#include <stddef.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/* ==================== 内存分配函数 ==================== */

/**
 * @brief 安全分配内存
 * @param size 分配大小
 * @return 分配的内存指针，失败返回NULL
 */
void* safe_malloc(size_t size);

/**
 * @brief 安全分配并清零内存
 * @param size 分配大小
 * @return 分配的内存指针，失败返回NULL
 */
void* safe_calloc(size_t count, size_t size);

/**
 * @brief 安全重新分配内存
 * @param ptr 原内存指针
 * @param size 新大小
 * @return 重新分配的内存指针，失败返回NULL
 */
void* safe_realloc(void* ptr, size_t size);

/**
 * @brief 安全释放内存
 * @param ptr 内存指针
 */
void safe_free(void* ptr);

/**
 * @brief 安全释放内存并置空指针
 * @param ptr 内存指针的地址
 */
void safe_free_and_null(void** ptr);

/* ==================== 内存操作函数 ==================== */

/**
 * @brief 安全复制内存
 * @param dest 目标内存
 * @param dest_size 目标内存大小
 * @param src 源内存
 * @param src_size 源内存大小
 * @return 实际复制大小
 */
size_t safe_memcpy(void* dest, size_t dest_size, const void* src, size_t src_size);

/**
 * @brief 安全移动内存
 * @param dest 目标内存
 * @param dest_size 目标内存大小
 * @param src 源内存
 * @param src_size 源内存大小
 * @return 实际移动大小
 */
size_t safe_memmove(void* dest, size_t dest_size, const void* src, size_t src_size);

/**
 * @brief 安全设置内存
 * @param dest 目标内存
 * @param dest_size 目标内存大小
 * @param value 设置值
 * @return 实际设置大小
 */
size_t safe_memset(void* dest, size_t dest_size, int value);

/**
 * @brief 安全比较内存
 * @param ptr1 内存1
 * @param ptr2 内存2
 * @param size 比较大小
 * @return 相等返回0，不相等返回非0
 */
int safe_memcmp(const void* ptr1, const void* ptr2, size_t size);

/* ==================== 内存检查函数 ==================== */

/**
 * @brief 检查内存是否为空指针
 * @param ptr 内存指针
 * @return 空指针返回true，否则返回false
 */
int is_null_pointer(const void* ptr);

/**
 * @brief 检查内存是否对齐
 * @param ptr 内存指针
 * @param alignment 对齐字节数
 * @return 对齐返回true，否则返回false
 */
int is_memory_aligned(const void* ptr, size_t alignment);

/**
 * @brief 检查内存大小是否有效
 * @param size 内存大小
 * @return 有效返回true，无效返回false
 */
int is_valid_memory_size(size_t size);

/* ==================== 内存调试函数 ==================== */

/**
 * @brief 获取内存使用统计
 * @param total_allocated 总分配大小输出
 * @param total_freed 总释放大小输出
 * @param current_allocated 当前分配大小输出
 * @param allocation_count 分配次数输出
 */
void get_memory_stats(size_t* total_allocated, size_t* total_freed, 
                      size_t* current_allocated, size_t* allocation_count);

/**
 * @brief 重置内存统计
 */
void reset_memory_stats(void);

/**
 * @brief 检查内存泄漏
 * @return 有泄漏返回true，无泄漏返回false
 */
int check_memory_leak(void);

#ifdef __cplusplus
}
#endif

#endif /* MEMORY_UTILS_H */
